<?php
/**
 *  Router Interface
 *  The router also presents an environment for controllers
 *
 *  Examples of usage:
 *  $router->useGET()->route("/fr/admin/sampleModule/subrequestController/")
 *  The environment of the called controller will be:
 *  $router->languageSelector: "fr"
 *  $router->moduleSelector: "sampleModule"
 *  $router->controllerSelector: "subrequestController"
 *  $router->modulesList: [admin => object(module), sampleModule => object(module)]
 *
 */
interface Yz_Router_Interface
{


    /**
     *  @param string $path
     *  @param Yz_Array|null $args additional arguments
     *  @return Yz_Controller_Interface
     */
    public function route( $path, Yz_Array $args=null );
    /**
     *  @param string|null
     *  @return chainable
     */
    public function routeRequest();

    /** set method to GET
     *  @return chainable
     */
    public function useGET();

    /** test if the route method is POST
     *  @return bool
     */
    public function isPOST();

    /** set method to POST
     *  @return chainable
     */
    public function usePOST();

    /** get the array of arguments
     *  @return Yz_Array
     */
    public function getArguments();

    /** get the last thrown Exception
     *
     */
    public function getException();

    /** get a HTTP_Request instance (obviously one per request)
     *  @return Yz_HTTP_Request_Interface
     */
    public function getRequest();

    /** get a HTTP_Response instance (obviously one per request)
     *  @return Yz_HTTP_Response_Interface
     */
    public function getResponse();

    /** get the web-prefix for the dynamically generated pages
     *      e.g. /yz-install-dir/
     *      or   /yz-install-dir/index.php (if mod_rewrite not detected)
     *  @return string always contains leading and trailing /
     */
    public function getWebPrefix();

    /** get the web-root for all the engine's paths
     *      e.g. /                  (if installed in DOCUMENT_ROOT)
     *      or   /yz-install-dir/
     *  @return string always contains leading and trailing /
     */
    public function getWebRoot();

    /** get the list of modules which were queried by the router
     *      in the course of processing the request
     *
     *  @return Yz_Hash
     */
    public function getModulesList();

    /** get the language as it was present in arguments
     *  @return string
     */
    public function getLanguageSelector();

    /** get the selector of the module, i.e. the part of path which was used
     *      to identify the current module
     *
     *  @return string
     */
    public function getModuleSelector();

    /** get the selector of the controller, i.e. the part of path which was used
     *      to identify the current controller,
     *      as supplied to the module.selectController()
     *
     *  @return string
     */
    public function getControllerSelector();


}
